home *** CD-ROM | disk | FTP | other *** search
/ Tricks of the 3D Game Programming Gurus / gurus.iso / DirectX / dx9sdkcp.exe / SDK (C++) / Samples / C++ / DirectShow / readme.txt < prev   
Encoding:
Text File  |  2002-11-19  |  22.6 KB  |  524 lines
  1. =============================================================================
  2. DirectShow SDK Samples README
  3. =============================================================================
  4.  
  5. The DirectShow SDK samples are subdivided into directories according to 
  6. their major function:
  7.  
  8.     BaseClasses
  9.     BDA
  10.     Capture
  11.     Common (shared source files)
  12.     DMO
  13.     DVD
  14.     Editing
  15.     Filters
  16.     Misc
  17.     Players
  18.     VideoControl
  19.     VMR
  20.     VMR9
  21.  
  22. There are also several Visual Basic 6.0 samples in the Extras\DirectShow\VB Samples
  23. directory.  Even if you don't develop applications with Visual Basic, we recommend
  24. that you review the Visual Basic sample executables.  Applications like
  25. SlideShow and Trimmer demonstrate many DirectShow Editing Servies (DES)
  26. capabilities that are not demonstrated in C++ samples.  The DexterVB tool
  27. (Timeline Explorer) is also useful for exploring and visualizing XML timelines
  28. used with DES.
  29.  
  30. See the "What's New" section below for information on new features in this release.
  31.  
  32.  
  33. Setting up the build environment
  34. --------------------------------
  35. In your Visual C++ build environment, be sure to set your Include and Lib 
  36. directories to point to the DirectX 9 SDK's include and lib paths.
  37. The DirectX SDK directories must be the first directories in the search path.
  38. Otherwise, you may encounter linker errors, since you would continue using
  39. the headers and libraries supplied with Visual C++ or with an earlier version
  40. of the Platform SDK.
  41.  
  42. Visual C++ project files are included for four targets:
  43.     Win32 Release, Win32 Debug, Win32 Release Unicode, Win32 Debug Unicode
  44.  
  45. For general information about building the DirectX SDK samples, see 
  46. "Compiling DirectX Samples and Other DirectX Applications" 
  47. in the "Programming DirectX with C/C++" section of the DirectX 9 documentation.
  48.  
  49. For DirectShow build information, see "Setting Up The Build Environment" in the 
  50. DirectShow "Getting Started" section of the DirectX documentation.
  51.  
  52.  
  53. Building the Samples
  54. --------------------
  55.  
  56. There are multiple ways to build the SDK samples, and we provide project
  57. files and workspaces for both Visual C++ 6.0 and Visual Studio.NET:
  58.  
  59.     1) Using the main DShow.DSW workspace (or DShow.SLN solution) for Visual C++
  60.     2) Using a workspace/solution provided for a category of samples
  61.     3) Building individual projects with their VC++ workspaces/solutions
  62.  
  63. 1) Using the Visual C++ Workspace or Visual Studio.NET Solution files:
  64.  
  65. The easiest way to build all samples is to open DShow.DSW (or DShow.SLN),
  66. which is installed to the DirectShow samples root directory.  This workspace
  67. includes references to each of the project files for the individual samples.
  68. You can select a project (in the FileView pane) and right-click to display a
  69. build menu for the project.  Select 'Build' to build a project and its 
  70. dependencies.  Note that if you select 'Build (selection only), you will not
  71. automatically build any dependencies (like the base classes, if required).  
  72.  
  73. You can also build or rebuild all of the projects together by selecting
  74. 'Build->Batch Build' from the Visual C++ main menu.  Projects included in
  75. this workspace know their dependencies and will build them if needed.
  76.  
  77. Some of the projects listed in the FileView pane do not build applications,
  78. but instead build support libraries used by other projects within the main
  79. workspace.  For example, the GargleDMO sample depends on the 'ControlBase'
  80. and 'MedParamBase' projects that are contained within the workspace.  
  81. If you build GargleDMO, Visual C++ will automatically build the 
  82. ControlBase and MedParamBase libraries if they need to be built, and those
  83. libraries will be linked into the GargleDMO DLL.
  84.  
  85.  
  86. 2) Using a workspace/solution provided for a category of samples:
  87.  
  88. We have also provided workspace/solution files for the sample subdirectories,
  89. so that you can build all of the samples of a particular type.
  90. For example, if you want to build only the Capture samples, you can
  91. open Capture\Capture.DSW (or Capture.SLN) and build the desired samples 
  92. individually or as part of a batch build.
  93.  
  94.  
  95. 3) Building Individual Projects:
  96.  
  97. You can open any of the provided project or workspace files in Visual C++
  98. if you want to build, modify, or debug an individual sample.  If you build
  99. outside of the DShow.DSW workspace, however, you might need to first build the
  100. DirectShow Base Classes, which are installed to the "BaseClasses" directory.
  101.  
  102. Note: The DirectMedia 6 SDK installed binaries for the BaseClasses
  103. (as strmbase.lib and the debug build as strmbasd.lib), which were compiled versions
  104. of the base classes previously installed into the SDK's classes\base directory.  
  105. DirectX now ships the source code for these base classes as a sample project,
  106. which allows you to modify the classes and build them with Visual C++.
  107. Since many of the samples (especially the sample filters) need to link with 
  108. STRMBASE.LIB (or STRMBASD.LIB), you must first build the base classes 
  109. to allow you to build other sample filters and applications that use them.
  110.  
  111. Don't forget to build both Debug and Release versions of the BaseClasses
  112. project if you intend to build both Debug and Release versions of the samples.
  113.  
  114.  
  115. Building Windows Media-related samples
  116. --------------------------------------
  117.  
  118. Building the Windows Media-enabled samples (AudioBox, ASFCopy, Jukebox, PlayWndASF)
  119. requires the Microsoft Windows Media Format SDK and a valid software certificate.  
  120. The SDK download page is located at:
  121.  
  122.     http://msdn.microsoft.com/workshop/imedia/windowsmedia/sdk/wmsdk.asp
  123.     
  124. with links to the SDK itself and information for obtaining a certificate.
  125. Once installed, the WMStub.lib and WMVCore.lib libraries should be copied into the
  126. [\DXSDK\Samples\C++\DirectShow\Common] folder in your DirectX SDK installation.
  127.  
  128. Because of the dependency on the Windows Media Format SDK, the project files
  129. for the affected samples are omitted from the main DirectShow Visual C++ 
  130. workspace files (dshow.dsw, dshow.sln) to prevent build issues.
  131.  
  132.  
  133. Windows Media support in SDK samples
  134. ------------------------------------
  135.  
  136. Because of the Windows Media Format SDK (and WMStub.lib) dependency, along with
  137. the extra filter connection and key provider code required, most of the
  138. DirectShow SDK samples (particularly the VMR samples) do not fully support
  139. rendering and playback of Windows Media content (ASF, WMA, WMV) by default.
  140. If you attempt to open a Windows Media file using one of these samples, you will
  141. be presented with a message box indicating the lack of Windows Media support, 
  142. with a pointer to the samples that do properly support Windows Media files.
  143.  
  144. The following samples provide the necessary extra code and project settings
  145. to enable proper Windows Media support (including unlocking of "keyed" files):
  146.  
  147.         - ASFCopy   - AudioBox  
  148.         - Jukebox   - PlayWndASF
  149.  
  150. Many of the other samples allow you to render ASF/WMA/WMV files with the legacy
  151. DirectShow ASF Reader filter, which is adequate for simple playback.  This method,
  152. however, does not offer the benefits of the newer Windows Media ASF Reader filter
  153. and does not support "dekeying" of keyed Windows Media content.
  154.  
  155. For more detailed information, see "Using DirectShow->Windows Media Applications"
  156. in the DirectX SDK documentation.
  157.  
  158.  
  159. Using Windows Media 9 Series (Corona)
  160. -------------------------------------
  161.  
  162. If you have installed the Windows Media Format 9 SDK (code named 'Corona'),
  163. then you should also review the SDK samples in that SDK (particularly the
  164. DSCopy and DSPlay samples).  Beginning with Windows Media 9 Series and
  165. the Windows Media Format 9 SDK, the WMStub.lib and key provider implementation code
  166. are no longer necessary.  This simplifies the sample code and removes the need
  167. to download and link with a WMStub library.
  168.  
  169. There are two samples in the DirectShow samples tree - Jukebox and Audiobox -
  170. that demonstrate some of the implementation differences between pre- and post-Corona
  171. systems.  These two samples have additional build targets for "WMF9" that
  172. remove the WMStub linking and define a preprocessor constant (TARGET_WMF9) 
  173. which disables the key-providing code.  These extra build targets are provided 
  174. to demonstrate compatibility with both system configurations.  
  175.  
  176. For more details, see the Windows Media Format 9 SDK documentation.
  177.  
  178.  
  179. Building for Windows XP
  180. -----------------------
  181. If you want to target Windows XP specifically to use its new features, 
  182. you must set WINVER=0x501 in the sample project file.  You must also 
  183. install the Windows XP Platform SDK, however, to ensure that you have the 
  184. latest header files.  For example, wxutil.cpp in the BaseClasses directory
  185. uses the new TIME_KILL_SYNCHRONOUS flag only if (WINVER >= 0x501).  This flag 
  186. is conditionally defined in the Windows XP Platform SDK in mmsystem.h, 
  187. but only if WINVER is also set to 0x501 when compiling.  
  188.  
  189. To prevent build issues, upgrade to the latest version of the Platform SDK.
  190.  
  191.  
  192. VMR9 Hardware requirements
  193. --------------------------
  194.  
  195. The VMR9 samples require a video card with a minimum of 16MB of video RAM.
  196. If your card has less than the minimum RAM, you may see failures when
  197. building filter graphs.  If that occurs, try lowering your display resolution.
  198.  
  199.  
  200.  
  201. =============================================================================
  202. What's New in DirectShow for DirectX 9.0
  203. =============================================================================
  204. November, 2002
  205. =============================================================================
  206.  
  207. New runtime features
  208. --------------------
  209.  
  210. - Video Mixing Renderer Filter 9 (VMR-9). - This new, redistributable 
  211.   rendering filter is similar in concept and design to the VMR that is 
  212.   available for Microsoft Windows XP Home Edition and Windows XP Professional. 
  213.   The VMR-9 is more powerful than the original VMR (now called "VMR-7") 
  214.   because it is fully compatible with the DirectX 9.0 graphics capabilities 
  215.   and it offers improved support for deinterlacing and ProcAmp control 
  216.   (brightness, contrast, hue, and saturation).
  217.  
  218. - New deinterlacing support in the DV Video Decoder filter. The DV Decoder 
  219.   filter now supports interlaced output, as well as deinterlaced output. 
  220.   Earlier versions of the decoder always deinterlace the video. 
  221.   With the new version, the interlaced video can be preserved and 
  222.   saved to file, or the video can be deinterlaced by the VMR, 
  223.   for improved rendering quality.
  224.  
  225. - New deinterlacing support in DirectX Video Acceleration. 
  226.  
  227. - AVStream driver development and runtime support on all platforms 
  228.   prior to Windows XP has been improved for close functional parity 
  229.   with Windows XP. A few AVStream and core Kernel Streaming 
  230.   behavioral differences still exist that are documented in the SDK.
  231.  
  232. - New encoder application programming interface (API) specification.
  233.   The Encoder API defines a standard, format-neutral way in which software 
  234.   or hardware encoders can communicate with applications and device drivers. 
  235.   IGetCapabilitiesKey is a new interface that filters can implement 
  236.   in order to enable applications to query for the filter's capabilities.
  237.  
  238. - MPEG-2 Sections and Tables Filter. This new filter enables an application 
  239.   to get PSI tables from an MPEG-2 transport stream. 
  240.  
  241. - Microsoft TV Technologies now supports DVB-T (terrestrial) and DVB-C (cable), 
  242.   in addition to DVB-S (satellite). For more information, see the SDK documentation.
  243.  
  244. - The Analog TV Tuner filter now supports adding new channel frequencies via the registry. 
  245.   This feature extends the existing mechanism for adding channel frequency overrides. 
  246.   For more information, see International Analog TV Tuning in the SDK. 
  247.  
  248. - DirectShow Editing Services (DES) now supports plug-in video resizing filters. 
  249.   For more information, see Providing a Custom Video Resizer in the SDK. 
  250.   
  251. - The DVD Graph Builder enables applications to use the VMR-9 through the 
  252.   IDvdGraphBuilder::RenderDvdVideoVolume method.  The DVD Navigator now supports 
  253.   playback of audio during fast forward; users can now watch a movie at speeds 
  254.   higher than 1x without raising the pitch of the audio track, if the decoder 
  255.   supports this feature.  The DVD navigator now provides faster DVD menu navigation.
  256.  
  257. - Video renderer no longer displays frame counters on debug builds.
  258.  
  259.  
  260. DirectShow SDK updates
  261. ----------------------
  262.  
  263. - Significant enhancements to the GraphEdit utility, including
  264.   Windows Media Certification (dekeying of non-DRM WM graphs), 
  265.   Filter Favorites menu, improved connect/disconnect from remote graphs, 
  266.   save/restore options, frame stepping, and color coding of connected filters.
  267.   XGR files are no longer supported by GraphEdit.
  268.  
  269. - Sample source code has been improved to enhance security, reliability,
  270.   and readability.  Support for Visual Studio.NET has also been added 
  271.   (VC.NET projects, solutions, etc.)
  272.  
  273. - Managed code for audio and video file playback.
  274.   The Microsoft.DirectX.AudioVideoPlayback managed code namespace provides 
  275.   playback and simple control of audio and video media. For more information, 
  276.   refer to the DirectX documentation for the managed DirectX components.  
  277.  
  278. - Numerous bug fixes and refinements for SDK samples and tools
  279.  
  280. - New Unicode Debug/Release build targets for Visual C++ 6.0 and 
  281.   Visual Studio.NET projects
  282.  
  283. - New and revised content in the SDK documentation
  284.  
  285. - New ProfileEnum tool (in Bin\DXUtils) lists the Windows Media system profiles
  286.   that are available for use on your system.  This tool is helpful if you
  287.   are creating Windows Media files (ASF,WMA,WMV) through DirectShow interfaces.
  288.  
  289. - The AMCap sample application now supports MPEG-2 program stream input, 
  290.   for example from analog TV Tuners that stream MPEG-2 content. A third-party 
  291.   DirectShow-compatible MPEG-2 decoder is still required to decode the streams. 
  292.  
  293. - Because using RenderFile() with monikers is no longer supported, the 
  294.   PlayCapMoniker sample demonstrates an alternate method (AddSourceFilter()).
  295.  
  296.  
  297. New DirectShow samples
  298. ----------------------
  299.  
  300. - Audiobox: Audio-only media player, similar to the Jukebox sample.
  301.   It supports Favorites and playback of Windows Media Audio and MP3 files.
  302.  
  303. - CaptureTex: Blends Texture3D and PlayCap to display incoming live
  304.   video on a rotating Direct3D surface
  305.  
  306. - CaptureTex9: Extends the CaptureTex sample to render live incoming video 
  307.   onto a Direct3D9 surface (a waving flag).
  308.  
  309. - CompressView: Demonstrates how to recompress an audio or video file 
  310.   using a different compression type.
  311.  
  312. - DSNetwork Filters: Implements an IP source filter and an IP rendering filter.
  313.   This filter set allows you to transmit/receive MPEG-2 data on a network.
  314.  
  315. - GrabBitmaps: Shows how to grab bitmaps from a video stream. 
  316.  
  317. - Metronome Filter: Sample filter that shows how to implement a reference clock. 
  318.  
  319. - PlayDVD: A simple windowed DVD player based on the PlayWnd sample.
  320.  
  321. - PlayWndASF: Added limited DRM support to the previous PlayWndASF sample.
  322.  
  323. - PSIParser Filter: Shows how to retrieve program information from an
  324.   MPEG-2 transport stream. 
  325.  
  326. - PushSource Filters: Set of three source filters that output a single
  327.   bitmap, a series of bitmaps, or a live desktop capture video stream.
  328.  
  329. - RenderLog: Creates a text log of DirectShow's progress while rendering a
  330.   media file. If you receive an error when you call IGraphBuilder::RenderFile, 
  331.   you can use this tool to create and view the log. 
  332.  
  333. - RGBFilters: Set of several sample source and transform filters useful for testing. 
  334.  
  335. - Texture3D9: Extends the Texture3D sample to play video on a DirectX 9 
  336.   texture surface, utilizing Direct3D9 features for more efficient rendering.
  337.  
  338. - TransViewer: Enables you to preview all of the DirectShow Editing Services 
  339.   transitions installed on your system. 
  340.  
  341.  
  342. New VMR-7 samples
  343. -----------------
  344.  
  345. - Blender: Demonstrates how to mix, blend, and manipulate two video streams. 
  346.  
  347. - MonitorInfo: Displays simple information about the available monitors
  348.   (using a VMR interface).
  349.  
  350. - Pip: Demonstrates how to create picture-in-picture effects using the VMR. 
  351.  
  352. - Text: Displays alpha-blended text over running video. 
  353.  
  354. - Ticker: Extends the Text sample to draw horizontally scrolling text
  355.   across the bottom of the video.  You can scroll text as a static bitmap
  356.   or as a dynamically generated bitmap created from user input.
  357.  
  358. - VMRMulti: Plays multiple video files over an animated Direct3D background. 
  359.   Each video stream is individually seekable.
  360.  
  361. - VMRXclBasic: Shows how to play video in full-screen exclusive mode.
  362.  
  363. - Watermark: Places an alpha-blended bitmap over the video and adds effects
  364.   (alpha strobe, scrolling, bitmap animation).
  365.  
  366. - Windowless: Demonstrates basic playback using the VMR's Windowless mode. 
  367.  
  368.  
  369. New VMR-9 samples
  370. -----------------
  371.  
  372. - VMR-9 versions of eight VMR-7 samples:
  373.     - Blender9, MonitorInfo9, Pip9, Text9, Ticker9, 
  374.       VMRPlayer9, Watermark9, and Windowless9
  375.   
  376. - VMR9Allocator: Renders video onto a rotating Direct3D surface
  377.  
  378. - BitmapMix: Uses the VMR9 to render video onto a Direct3D9 surface while
  379.   blending a bitmap that can be moved via mouse input
  380.  
  381. - MultiVMR9: Demonstrates using a custom VMR9 Allocator-Presenter in a
  382.   multi-graph environment.  There are three folders in this project, including
  383.   a support DLL, a MultiPlayer sample, and a 3D GamePlayer sample that integrates
  384.   video playback into a Direct3D game environment.
  385.   
  386.  
  387. Removed Samples
  388. ---------------
  389.  
  390. - JukeboxASF has been removed.  Its Windows Media support has been merged 
  391.   into the Jukebox sample. 
  392.  
  393. Sample media files
  394. ------------------
  395.  
  396. The video codec used in highway.avi and ruby.avi has been changed to Cinepak.
  397. This was done to enable playback on clean installations of Windows XP SP1,
  398. which no longer ships the Indeo codecs.
  399.  
  400.  
  401. =============================================================================
  402. What's New in DirectShow for DirectX 8.1
  403. =============================================================================
  404. September, 2001
  405. =============================================================================
  406.  
  407. There have been considerable improvements made to the DirectShow content
  408. for the DirectX 8.1 SDK.  Below is a brief summary of the updates.
  409.  
  410.  
  411. Improvements to existing samples
  412. --------------------------------
  413. There have been many enhancements and refinements to the existing
  414. DirectX 8.0 samples for this release, including:
  415.  
  416. - New features and functionality
  417. - Numerous bug fixes, including Windows XP support issues
  418. - UNICODE and IA64 support
  419. - ASF-enabled versions of the PlayWnd and Jukebox samples
  420. - Clean compilation with Warning Level 4
  421. - Improved video window repainting for Jukebox-style MFC applications
  422. - Updated resource files and version information blocks
  423. - Digital Video sample (Capture\DVApp) was rewritten to take 
  424.   advantage of the ICaptureGraphBuilder2 interface to build its graphs.
  425.  
  426.  
  427. New DirectShow samples
  428. ----------------------
  429. - Audio Capture         (Capture\AudioCap)
  430. - DMO-enabled Player    (Players\PlayDMO)
  431. - DMO Enumerator        (Misc\DMOEnum)
  432. - Filter Mapper         (Misc\Mapper)
  433. - Grabber Sample Filter (Filters\Grabber) (modified from DirectX 8 SampleGrabber)
  434. - JukeboxASF            (Players\JukeboxASF)
  435. - PlayCap with Moniker  (Capture\PlayCapMoniker)
  436. - PlayWndASF            (Players\PlayWndASF)
  437. - Still Image Viewer    (Players\StillView)
  438. - Utility source code and routines in the DirectShow\Common directory
  439.  
  440.  
  441. New DirectShow samples for Windows XP
  442. -------------------------------------
  443. Windows XP provides new functionality that is not present in downlevel
  444. operating systems (Windows 9x, Windows 2000).  The VMR and VideoControl
  445. directories provide samples to demonstrate using the new Video Mixing
  446. Renderer and the new Microsoft Video Control (for use with the Windows
  447. Driver Model and Broadcast Driver Architecture).
  448.  
  449. The new samples include:
  450.  
  451. - Video Control - C++, Visual Basic, and HTML samples of rendering
  452.   ATSC, DVB, and Analog television in a Windows application.  The
  453.   new Video Control encapsulates much of the new functionality and
  454.   aids developers in creating television-enabled applications.
  455.  
  456. - Video Mixing Renderer (VMR):
  457.   - Cube
  458.   - Renderless
  459.   - Text Player
  460.   - VMR Mix
  461.   - VMR Player
  462.   - VMR Exclusive Mode (VMRXcl)
  463.  
  464. See the VideoControl and VMR directories for more detailed information 
  465. about these new samples.
  466.  
  467.  
  468. Updated Documentation
  469. ---------------------
  470. The DirectShow documentation has been significantly enhanced for 
  471. DirectX 8.1.  It adds information for the new features available in
  472. Windows XP and expands on previously presented material for the
  473. Microsoft TV Technologies.
  474.  
  475.  
  476. Modified SampleGrabber filter source code
  477. -----------------------------------------
  478. There have been several requests for Microsoft to publish the source
  479. code for the popular SampleGrabber filter.  To that end, we now provide
  480. a modified (simpler) version of the sample grabber filter, which uses 
  481. a new GUID and new CLSID to prevent collisions with the original 
  482. DirectX 8.0 filter.  You can review and modify the source code for this 
  483. filter and use it in your own applications.  See the Filters\Grabber 
  484. directory for more information.
  485.  
  486.  
  487. Windows XP support in header files
  488. ----------------------------------
  489. DirectX 8.1 provides support for the following Windows platforms:
  490.     - Windows 98, Windows 98 Second Edition, Windows Millennium Edition
  491.     - Windows 2000
  492.     - Windows XP
  493.  
  494. To enable Windows XP features and to utilize the new portions of the
  495. affected headers, set the Windows version to 0x501 (the Windows XP
  496. version) in your Visual C++ project files.
  497.  
  498.  
  499. Runtime improvements
  500. --------------------
  501. The DirectX 8.1 binaries and redist files benefit from various bug fixes
  502. made since the DirectX 8.0 release, including a large subset of the 
  503. modifications that were made for Windows XP.
  504.  
  505.  
  506. Revised GraphEdit application
  507. -----------------------------
  508. The GraphEdit utility received several improvements, particularly 
  509. with respect to its user interface, menus, and toolbar.  Additionally,
  510.  
  511. - Graph resizing code (View->xxx %) handles all sizes correctly, and 
  512.   you can resize your graphs using the menu, keyboard +/- keys, and 
  513.   Ctrl+MouseWheel.  
  514.  
  515. - You can optionally disable the seek bar (and its timed updates), which 
  516.   has been known to cause difficulty when debugging filters with GraphEdit.  
  517.  
  518. - To preserve screen real estate, source and file writer filters displayed 
  519.   in GraphEdit will now only display their simple root filenames as the 
  520.   filter name, instead of displaying the fully qualified path name.  
  521.   For example, a file source for the file 
  522.   "C:\DXSDK\samples\Media\lake.mpg" would display as "lake.mpg".
  523.  
  524.